---
title: Shadowing
description: Guide for shadowing theme components and files
date: 24 June 2020
---

<PageDescription>

In the world of Gatsby themes,
[component shadowing](https://www.gatsbyjs.org/blog/2019-04-29-component-shadowing/)
is an extremely powerful way for developers to provide their _own_ components
for the theme to use over the defaults. You can shadow any file that is
processed by webpack. This includes sass files, mdx files, and the react
components themselves.

</PageDescription>

## Caveats

If you completely shadow a file you won’t get future updates to that individual
file. These are some golden rules to make sure you stay as close to the theme as
possible and not forgo future updates.

1. Open a
   [quick issue](https://github.com/carbon-design-system/gatsby-theme-carbon/issues/new)
   in the gatsby-theme-carbon repo to make sure we’re not working on your
   change.

1. Shadow as few files as you can to achieve your goal. If you can shadow just a
   single file, that’s ideal.

1. If you do end up shadowing a component, please tell us! We might use it to
   inform future development.

## Shadowing basics

In order to shadow a component in the theme, all you need to do is place a file
in the `src/gatsby-theme-carbon` in your project. The file should have the same
name as the file you’re shadowing.

In order to place your own title in the Header component:

1. Create a file at the same directory as the component you wish to shadow.
   Everything after `src/gatsby-theme-carbon/` refers to the
   [src directory of gatsby-theme-carbon](https://github.com/carbon-design-system/gatsby-theme-carbon/tree/main/packages/gatsby-theme-carbon/src).

1. Import the component you wish to shadow by providing the full url pointing at
   the component within the theme

1. Your component will **receive the same props** as the one you’re shadowing.
   You’ll can log those props to see if you’ll need any of them

1. Regardless, you should _ALWAYS_ spread the extra props into the original
   component, this allows the core component to function as needed. Even if it
   doesn’t receive any props now, it might in the future.

1. Provide your new, custom component as the default export

```jsx
import React from 'react';
import Header from 'gatsby-theme-carbon/src/components/Header';

const CustomHeader = (props) => (
  <Header {...props}>
    <span>Gatsby theme</span>&nbsp;Carbon
  </Header>
);

export default CustomHeader;
```

## Components you’ll need to shadow

We’ve already provided pre-shadowed, dummy components however these are the ones
you’ll definitely need to shadow.

| Component     | Path                                                                                                                                                                                                                | Description                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| ResourceLinks | [`src/gatsby-theme-carbon/components/LeftNav/ResourceLinks.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/LeftNav/ResourceLinks.js) | The bottom links on the SideNav, pass `shouldOpenNewTabs` to open links externally |
| Footer        | [`src/gatsby-theme-carbon/components/Footer.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/Footer.js)                               | The links and content at the bottom of each page                                   |
| Header        | [`src/gatsby-theme-carbon/components/Header.js`](https://github.com/carbon-design-system/gatsby-theme-carbon/blob/main/packages/example/src/gatsby-theme-carbon/components/Header.js)                               | The text in the top left corner of the UI Shell                                    |
